GRAPHTAL

Section: User Commands (1)
Updated: October 27, 1992
Index Return to Main Contents

NAME

graphtal - L-system generation program

SYNOPSIS

graphtal [options] [file]

DESCRIPTION

graphtal is a tool for manipulating spT0L-systems (context free, table oriented L-systems with stochastic productions). graphtal reads a file containing an L-system description and starts the interpretation. In addition, graphtal is able to interpret the result graphically, producing different kinds of output.

The main reference for the program is the book The Virtual Laboratory: The Algorithmic Beauty of Plants by P. Prusinkiewicz and A. Lindenmayer. The language used in graphtal is different from the one in the book and will be described completely in this document.

The following sections describe how to run graphtal, the input format accepted and turtle commands implemented.

NOTATION

* [thing] Optional item.
* <Thing> Production.
* Thing Number or String.
* (thing) Default value(s).
* thing Keyword.

SECTION 1: RUNNING GRAPHTAL

OPTIONS

Command line options override the settings in the input file. The following options are accepted:

-O outfile: Sets the output file name.
-R xres yres: Render at given resolution. The default is set to (400, 400).
-E x y z: Set eyepoint vector. The default is set to (0 1 0).
-L x y z: Set lookat vector. The default is set to (0 0 0).
-U x y z: Set up vector. The default is set to (0 0 1).
-f angle: Set field of view. The default is set to (45)
-Dname: Define name as 1 (cpp option).
-Dname=def: Define name as "def" (cpp option).
-d drivername: Set the output device driver. The default driver is (x11simple).
Drivers included:
   no        No turtle interpretation.
   example   Example driver.
   bbox      Calculate bounding box and viewing
             parameters.
   rayshade  Rayshade driver.
   x11simple Simple line drawing driver for X11.
   x11wire   Wire frame driver for X11.
   flat      Simple z-buffering.
-c: Toggle cone spheres generation. If cone spheres are enabled, line segments are connected with spheres. The default is (no cone sphere generation).
-s: Show the defined hulls. The default is set to (no).
-v: Verbose output. The default is set to (not verbose).
-q: Run quietly. The default is set to (don't be quiet).
-l: Print L-system definition. The default is set to (don't print it).
-p: Print resulting module string. The default is set to (don't print the modules).
-e: Erase module after turtle interpretation. The default is set to (don't erase).
-h: Help: print the command line options.

SECTION 2: LANGUAGE DESCRIPTION

graphtal accepts a grammar describing spT0L-systems, with the following features:

*  D0L-systems (DOL),


*  tables of productions (TOL),


*  productions with parameters (pTOL),


*  stochastically applied productions (spTOL),


*  global and local constants,


*  hull definitions (turtle interpretation with regard to
   these hulls),


*  production parameters may be strings or real values.

All these features may be freely combined.

CASE SENSITIVE

graphtal is case sensitive.

NAMES

Two types of names are accepted: module names, and variable names. Variable names follow the rules for C identifiers: arbitrarily long strings chosen from the character set [A-Za-z_0-9], with digits disallowed as the leading character. Module names are variable names or one of the following special characters:

 + - ^ & \ / | $ [ ] { . } ~ %.

EXPRESSIONS

Expressions generally follow the rules of C expressions. Variable names, string constants and numeric values are operands.

The predefined variables and constants:

- constants

M_PI, M_PI_2, M_PI_4, M_E, M_SQRT2, M_LN2, M_LN10, true, false

- variables

turtlex, turtley, turtlez (current position of turtle)

and the operators and functions:

- logical operators:

!, ||, &&, ==, !=, <, <=, >, >=

- arithmetic operators:

:: (scope operator), +, - (unary and binary), *, /, % (remainder), ** (exponentiation), ^ (exponentiation)

- functions

sin, cos, tan, asin, acos, atan, abs, sqrt, exp, log, log10, rand (generate a random number in the range (0,1) ), gauss (generate a gaussian random number in the range (0,1) ), if (if(a,b,c) <=> if (a) b else c)

graphtal tries to simplify each expression by evaluating constant subterms. For example the expression

sqrt(2*2)*rand() is reduced to 2*rand().

Reals and strings may be combined and string/real, real/string promotion is done at evaluation time according to the following rules:

Operators:
- real/real No promotion necessary.

- real/string

Convert the second argument to real if possible, otherwise convert the real argument to string -> string/string calculations are applied.

- string/real

Convert the second argument to string and do string/string calculations.

- string/string

Logical operators do string comparison. The arithmetic operator + is defined as string concatenation. For the other arithmetic operators the arguments are converted to real and real/real calculation is done. If this is impossible, an error occurs.

Functions:
All the function arguments are converted to real. If this
is impossible, an error occurs.

LSYSTEM

graphtal accepts a single file in the format described below from standard input or a given file. The L-system description is parsed and the tables of productions are applied to the axiom as specified within the attributes section. The resulting module string controls a 3d turtle and produces an image. In EBNF an L-system looks like this:


LSystem: 
     lsystem Name [ <GlobalConstants> ] [ <Hulls> ] 
          <Tables> <Attributes> ;

GlobalConstants:
     <ConstantsDef>

CONSTANTS

An L-system description file may contain any number of constants. The scope of a local constant is the table where it was defined, whereas the scope of global constant is the whole L-system description. Because local constants may hide the name of a globally defined constant, the scope operator (::) may used to have explicitly access to global scope.


Example:
     lsystem test;
     /* definition of global constants */
     const a = 5*sin(M_PI);
           b = a*a;

     table one {
       /* local constant definition within a table, */
       /* access to global constant via scope operator */
       const a = ::a;
       ...
     };


ConstantsDef:
     const <Constants>

Constants:
       <Constant>
     | <Constants> <Constant>

Constant:
     Name = <expression> ;

HULLS

Hulls are a special feature of graphtal, which allows a global control of growth in the interpretation process. A hull consists of primitives . Any number of hulls may be defined. If a hull is activated, the turtle moves with regard to that hull, i.e. when the current path of the turtle intersects a hull primitives, the interpretation is stopped and one of two possible procedures is executed:

*  reflect the turtle on the surface 
   we hit (regarding a reflectance factor)
*  cut the current branch

The definition of primitives has been adapted from Craig Kolbs rayshade. This allows a user to include already defined objects into the L-system description file. As an example the definition of a house could affect the growth of a tree in the way, that the tree may not penetrate the house.


Example:
     hull aHull {
       plane 0 0 0 0 0 1
       cylinder 1 0 0 0  /* unit cylinder */
                  0 0 1
         scale 1 1 2
         translate 0 0 5
     };


Hulls:
       <Hull>
     | <Hulls> <Hull>

Hull:
     hull Name { <Primitives> } ;

Primitives:
       <Primitive> [<Transforms>]
     | <Primitives> <Primitive> [<Transforms>]
     
Primitive:
       sphere   Radius Xpos Ypos Zpos
     | triangle Xv1 Yv1 Zv1 Xv1 Yv1 Zv1 Xv1 Yv1 Zv1
     | plane    Xpos Ypos Zpos Xnorm Ynorm Znorm
     | cylinder Radius Xbase Ybase Zbase Xapex Yapex Zapex
     | cone     Rbase Xbase Ybase Zbase 
                Rapex Xapex Yapex Zapex

Transforms:
     <Transform>
     <Transforms> <Transform>

Transform:
     translate  Xtrans Ytrans Ztrans
     scale      Xscale Yscale Zscale
     rotate     Xaxis Yaxis Zaxis Degrees
     transform  A  B  C
                D  E  F
                G  H  I
               [Xt Yt Zt]

Arguments for the primitives and transformations are numeric values and constants.

TABLES

A table is a collection of productions. Any number of tables may be defined within a description file. Designing an L-system in a table oriented manner, allows the user to modularize the productions. For instance the L-system of a tree could consist of two tables, one for the branches and another for the leafs. Please look at the examples for further details.

Tables:
       <Table>
     | <Tables> <Table>

Table:
     table Name { <Constants> <Productions> } ;

PRODUCTIONS

graphtal allows the definition of productions with parameter and probabilities. All the productions are context free. It's better to show some examples instead of giving long explanations:

A production in a D0L-System:

MatchingModule -> any any any;

A production with parameters and condition:

F(l) : l > 0.5 -> F(l2) A(l+1);

An "empty" production (eat the module):

Leaf(season) : season == "winter" -> ;

A stochastic production:

Branch(l) -> (0.2) F(l)
          -> (0.5) F(l/2) F(l/2)
          -> (0.3) ;

And now the detailed EBNF for <Productions>:

Productions:
       <Production>
     | <Productions> <Production>

Production:
     <Predecessor> [ <Condition> ] <Successors> ;
       
Predecessor:
     Name [ <Arguments> ]

Arguments:
     ( <Parameters> )

Parameters:
       Name
     | <Parameters> , Name

Condition:
     : <Expression>

Successors:
       <Successor>
     | <Successors> <Successor>

Successor:
     -> [ <Probability> ] [ <Modules> ]

Modules:
       <Module>
     | <Modules> <Module>

Module:
     Name [ ( <ExpressionList> ) ]

Probability:
     Number

ExpressionList:
       <Expression>
     | <ExpressionList> , <Expression>

ATTRIBUTES

In the attributes section of the L-system description file, all the parameters are set, which affect the interpretation process. The axiom and derivation attributes have to be declared. Here's the list of attributes:

Attributes:
     attributes { <AttributesList> } ;

AttributesList:
       derivation <Derivations> ;
     | axiom <Modules> ;
     | roll <Expression> ;
     | turn <Expression> ;
     | pitch <Expression> ;
     | angle <Expression> ;
     | forward <Expression> ;
     | randomize [ <Expression> ] ;
     | tropism <Expression> , <Expression> , <Expression> ;
     | weight <Expression> ;
     | eye <Expression> , <Expression> , <Expression> ;
     | lookat <Expression> , <Expression> , <Expression> ;
     | up <Expression> , <Expression> , <Expression> ;
     | fov <Expression> ;
     | coneres Number ;
     | sphereres Number ;

Derivations:
       Name [ <Steps> ]
     | <Derivations> , Name [ <Steps> ]

Steps:
       ( <Expression> )
     | ( infinity )

DERIVATION

The derivation attributes specifies the tables to be applied to the axiom. Global constants may be used in step definitions. Examples:

Apply table1 once and table2 10 times to the axiom:

derivation table1, table2(10);

Apply table1 once to the axiom and table2 as long a production of the table matches any module in the module string.

derivation table1(1), table2(infinity);

AXIOM

Set the axiom of the L-system. Global constants may be used in expressions.

ROLL, TURN, PITCH, ANGLE, FORWARD

Set the default values for turtle commands without parameters. pitch, roll and turn specifies the default rotation angle for one of the three rotation operations. The command angle sets pitch and turn, roll to the same rotation angle. The forward command specifies the default step for turtle movements.

RANDOMIZE

Initialize the random number generator.

randomize;         calls srand with the current time.
randomize number;  calls srand with number.

TROPISM, WEIGHT

Set analytic tropism function (see also TROPISM in section 3). The tropism vector and the weight function may depend on the turtle position in the interpretation process by using the predefined variables tx, ty and tz. This can't be done within the production rules, because the parameters of the modules are determinated before the interpretation process starts.

EYE, LOOKAT, UP, FOV

Set viewing parameters. graphtal uses a simple model, similar to Craig Kolbs rayshade.

CONERES, SPHERERES

Set resolution for cone and sphere tesselation. The values set are used by the flat and wire frame device driver.

OTHER FEATURES

COMMENTS

C-style (delimited by /* and */) and C++-style comments (delimited by //) are accepted at any point in the input.

CPP

cpp (C language preprocessor) is invoked as the first pass of any L-system interpretation. Therefore you may add includes, defines and macro definitions to the input file. The command line option -D (see OPTIONS) attaches a value to a name which may be used as an additional parameter in the i-system description. This is useful for animations. See the examples for further details.

SECTION 3: TURTLE COMMANDS

A lot of module names have their special meaning the interpretation process. Here's the list of module bindings in graphtal:

BASIC MANIPULATIONS

F: Move turtle forward drawing a line (cylinder) from start to end point.
F(3) moves turtle forward 3 steps. F move a default step, which is initially set to 10 but may be redefined in the attributes section with the command forward (see ATTRIBUTES).
f, G: Move turtle forward without drawing a line. For examples see F.
pt, ^: Rotate turtle around its left axis in positive direction, i.e. counter clock wise (pitch).
pt(45) or ^(45) pitches the turtle 45 degrees around it's left axis. pt pitches the turtle around it's left axis by the default rotation angle, which is initially set to 45 degrees, but may be changed in the attributes section with the commands pitch or angle.
&: Pitch turtle in negative direction (clock wise).
ro, /: Rotate turtle around it's heading in positive direction (roll). Default is 45 degrees, but may be changed in the attributes section with the commands roll or angle. See pitch for examples.
\: Roll the turtle in negative direction. For examples see pitch.
tu, -: Rotate turtle around it's up direction in positive direction (turn). Default is 45 degrees, but may be changed in the attributes section with the commands turn or angle. See pitch for examples.
+: Turn the turtle in negative direction. See pitch for examples.
rv, $: Rotate turtle vertically, i.e. align the turtle's heading to a vertical position.
|: Reverse the turtle -> tu(180).
[: Push current turtle state on the turtle stack (start branch).
]: Set turtle state to the value on top of turtle stack (end branch).
wi: Set line width to new value. Default width is 1. The line width command specifies the radius(!) of the cylinder which a F would draw.
wi(10) -> new line width is 10 (= radius of the cylinder to be drawn, therefore the width of the cylinder is 20).
%: Cut a branch. If an % symbol is detected by the turtle interpreter all the following modules are ignored until a ] (end branch) symbol. Subbranches are deleted as well.
G % F F [ F ] ] pt F is interpreted as G pt F.

GEOMETRIC PRIMITIVES

{: Start polygon. Polygon definitions may be nested.
{ . F . tu(45) F . } generates a triangle.
sv, .: Save current turtle position as polygon vertex.
}: End of polygon definition.
poly: Draw a polygon with given vertices.
poly(0,0,0, 0,10,0, 10,10,0, 10,0,0) generates a polygon with 4 vertices.
tri: Draw a triangle with given vertices. The first 9 parameters are regarded as the triangle vertices, the rest is ignored.
s: Draw a sphere at current location with given radius (default is 1).
s(25) draw a sphere with radius 25 at turtle position.

MACROS AND LIBARY OBJECTS

graphtal supports the definition of macros (subobject) and library object (predefined objects). These features depend on the device driver used. Macros are supported by the wire frame and the rayshade device drivers. Library objects are known to the rayshade driver. The other device drivers do not support these features and ignore the corresponding modules.

sm

Start a macro definition. Macros may not be nested. While defining a macro, all the geometric primitives generated are collected by the device driver. This process comes to an end when the end macro (em) command occurs in the module string.

sm("leaf") F em
Generate a macro with the name "leaf" containing a single cylinder object.

em

End of macro definition. See start macro.

xm

Execute a macro. A already defined macro can be execute at any point of the interpretation process. The geometric primitives of the choosen macro are transformed according to the turtle position and the scale factor given by the execute macro command.

xm("leaf")
Include the primitives of the macro "leaf" at the turtle location.

xm("leaf", 0.5)
Scale the primitives of the macro "leaf" and include them at the turtle location.

lib

Include a predefined library object at the current turtle location. An additional scaling factor may be specified.

lib("apple")
Generate the library object "apple" at the current turtle location.

lib("apple", 1.2) Generate the library object "apple" at the current turtle location and scale it by 1.2.

RENDERING ATTRIBUTES

texture: Set texture attributes for the following primitives. This feature is implemented for the rayshade driver, all the others ignore it. The implementation is very simple: the user may give a string describing the texture to be applied. It's the device driver's task to react in an appropriate manner.
texture("texture bump 0.3")
The rayshade driver adds to each following primitives the string "texture bump 0.3".
co: Set the drawing color. All the known colors are stored in the file "colors.def" each line in the format "R G B colorName". Any number of colors may be added to this file. The defined colors are taken from the X11 distribution.
co("ivory") change the color to "ivory".

TROPISM

With tropism vectors it's possible to manipulate the growth of the L-system towards a defined direction. For example a plant growing towards the position of the sun. If the tropism vector is the zero vector or the tropism weight equals zero, then tropism calculations are disabled.

t: Set tropism vector (see also attributes TROPISM). Initially tropism computations is disabled and the tropism vector is set to (0,0,-1).
t(1,0,0) set tropism vector to (1,0,0). t(1,0,0,0.5) set tropism vector to (1,0,0) and weight factor to 0.5 -> enable tropism computation.
we: Set weight factor for tropism computation. Initially the weight factor is set to 0.5. A factor of 0 disables tropism calculation.

HULLS

As explained in section 2, the turtle can react in two different ways to a hit with a hull. The reflect behaviour is specified through the ah command, and the cut behaviour through cb.

ah

Activate a hull defined in the L-system description and set the reflectance factor.

ah(nameOfTheHull, reflectanceFactor)
Activate the hull with the name "nameOfTheHull". If the turtle hits a hull primitive, reflect according to reflectanceFactor (0=no reflectance, 1=full reflectance).

ah("house") activate the hull "house", reflectance factor is 1 as default.

ah("house", 0.3) activate the hull "house", reflectance factor is 0.3

dh

Deactivate the hull set (if any).

cb

Enable/disable cutting of branches when a hull primitive is hit.

cb or cb(1) cut the branch when hull is hit. cb(0) don't cut (default).

SECTION 4: DEVICE DRIVERS

EXAMPLE DEVICE

The example driver produces a ASCII dump of the primitives generated. It shows the easiest way to implement a driver.

BBOX DEVICE

The bbox driver computes the bounding box and gives a hint for the viewing parameters of the objects defined by the L-system description. This is useful for the flat device, which does no automatic view computations.

LINE DEVICE (X11)

This driver generates a simple line drawing of the object defined by the L-system. Line width, color, textures, spheres, macros and library object are not supported by this driver. Viewing parameters are automatically set, when none are provided by the user.

WIRE DEVICE (X11)

The wire device driver draws a more realistic image of the object than line device. Not supported are colors, textures and library objects. Viewing parameters are also set automatically, when none are provided.

FLAT DEVICE

The flat device works with a z-buffer algorithm, which is able to shade convex and concave polygons. Shading calculations are done with regard to the light source located at the eyepoint. The driver does not depend on the number of polygons, therefore even very large scenes can be visualized. As a drawback of this feature, the viewing parameters have to be provided by the user (use BBOX DEVICE to calculate them). Textures and library objects are not supported by this driver. The output of the rendering process is an image in ppm format (portable pixmap). There are two ways to capture the image:

graphtal -d flat ... -O tree.ppm tree.lsys

graphtal -d flat ... tree.lsys > tree.ppm

RAYSHADE DEVICE

The rayshade device is the most complete of all the drivers. It generates output for the raytracer rayshade. The driver produces at least two output files:

graphtal -d rayshade anExample.lsys
generates the files default.ray and default.ray.def

graphtal -d rayshade -O anExample.ray
generates the files anExample.ray and anExample.ray.def.

The file name.ray contains the options for the rendering process and in the name.ray.def file the geometric primitives are stored. For each macro definition, the rayshade driver produces it's own file with the name macrName.ray.def. If library objects are used, a file with the name libraryName.ray.lib must be provided by the user for each object.

ENVIRONMENT

With the environment variable COLORFILE the path and the name for the color file can be specified. With

setenv COLORFILE ~/includes/colors.def

graphtal will read the color definition file specified, instead of the default (= colors.def in the working directory).

AUTHOR

Christoph Streit (streit@iam.unibe.ch)

COPYRIGHT NOTICE

This software may be freely copied, modified, and redistributed provided that this copyright notice is preserved on all copies.

You may not distribute this software, in whole or in part, as part of any commercial product without the express consent of the authors.

There is no warranty or other guarantee of fitness of this software for any purpose. It is provided solely "as is".

OTHER COMMENTS

Please send bugs (accompanied by L-systems causing them), interesting L-systems for inclusion in the release, enhancements, and suggestions to the author via email.